<HTML><HEAD><TITLE>Installing BRL-CAD</TITLE></HEAD><BODY>
<H1>Installing BRL-CAD</H1>

<p><b>*** PLEASE READ ***<BR>
THESE INSTALLATION INSTRUCTIONS ARE NO LONGER RELEVANT.<BR>
PLEASE SEE THE README OR INSTALL FILES IN THE SOURCE DISTRIBUTION.<br>
They are included for historical reference ONLY<br>
</b></p>

<P>
This document exists to help you install the BRL-CAD Package. With
approximately 435,000 lines of source code, and support for over a dozen
hardware platforms, the configuration is important.
It would be best if you read
these directions first. However, it would be quite understandable if
you were more eager to press ahead than to read this long paper.
If you choose to start compiling now,
the commands to run are presented here.
Please, if anything seems wrong, pause to finish reading the directions.
<pre><b>
        mkdir /usr/brlcad
        mkdir cad
        cd cad
        tar x</b>              # 'tar xo'   on System V<b>
        sh machinetype.sh -v
        sh setup.sh
        sh gen.sh all
        sh gen.sh install
</b></pre>
<p>
If you need to install the software somewhere other than /usr/brlcad,
(given as /a/b/c in this example,) follow this procedure:
<pre><b>
        mkdir /a/b/c
        mkdir cad
        cd cad
        tar x</b>               # 'tar xo'   on System V<b>
        sh machinetype.sh -v
        sh newbindir.sh /a/b/c
        sh setup.sh
        sh gen.sh all
        sh gen.sh install
</pre>
<H2>DISTRIBUTION TERMS</H2>
<p>
This software is an unpublished work that is not generally available
to the public, except through the terms of a limited distribution
agreement.
Please recall that to obtain this software, you agreed that
before using the software at additional sites, or for permission to
use this work as part of a commercial package, you would first obtain
authorization from ARL.
<h2>INTRODUCTION</H2>
<p>
The BRL-CAD Package software is distributed only in source code form.
There are quite a number of advantages to this.
The most important advantage is that only a single distribution tape
has to be prepared;  this distribution tape contains the complete
software for all currently supported machines.
All a BRL-CAD recipient needs to do is compile the source
code, and install the resulting binaries.
The second most important advantage of a source-code-only distribution
is that it gives you complete control of your destiny.
If you need to add a feature, change something, or fix a bug,
you have everything required.
Since ARL is unable to offer any kind of support of this software to
non-Government recipients, distributing full source code ensures
that you need not become "stuck".
<P>
This software is generally used in one of three ways:
<ul>
<li>For production use,
<li>For the RT ray tracing benchmark, or
<li>For exploration, to get acquainted with the software.
</ul>
<P>
Each of these different types of use will require slightly different
configuration of the software.
By default, the software is pre-configured for production use,
to make installation most convenient for the primary user community.
However, the modifications required for non-production use are
slight, and are called out in great detail in the ensuing sections.
<P>
The BRL-CAD Package has been ported to a great many different
machines throughout its lifetime.
Every machine / software version combination will fall into
one of these three categories:
<p> a)
For every configuration that we have available to test with at BRL,
the software has been designed to install automatically, without
need for any modifications to the configuration files.
The hardware/software configurations
which are known to have "automatic support" in this release
are listed in this table,
along with the
default configuration specified in <b>Cakefile.defs</b>:
<center>
<table border=1>
<tr><th>MTYPE</th><th>Hardware</th><th>Software</th><th>Framebuffer</th><th>MGED</th>
<tr></tr>
<tr><td>c1</td><td>Convex C1</td><td>UNIX 6.2.32.2</td><td>net</td><td>-</td></tr>
<tr><td>xmp</td><td>Cray X-MP,Y-MP,C-90</td><td>UNICOS 8</td><td>net,X11</td><td>X11</td></tr>
<tr><td>cr2</td><td>Cray-2</td><td>UNICOS 7</td><td>net,X11</td><td>X11</td></tr>
<tr><td>alpha</td><td>DEC Alpha</td><td>OSF/1 V3.0</td><td>net,X11</td><td>X11</td></tr>
<tr><td>vax</td><td>DEC VAX-11</td><td>Berkeley 4.2 BSD, 4.3 BSD</td><td>net</td><td>-</td></tr>
<tr><td>bsdi</td><td>IBM PC</td><td>BSDI</td><td>net,X11</td><td>X11</td></tr>
<tr><td>li</td><td>IBM PC</td><td>Linux</td><td>net,X11</td><td>X11</td></tr>
<tr><td>nb86</td><td>IBM PC</td><td>NetBSD/i386 1.0</td><td>net,X11</td><td>X11</td></tr>
<tr><td>5d</td><td>SGI 4D</td><td>Irix 4.0.5</td><td>sgi,net,X11</td><td>sgi,X11</td></tr>
<tr><td>6d</td><td>SGI 4D</td><td>Irix 5.2</td><td>sgi,net,X11</td><td>sgi,X11</td></tr>
<tr><td>7d</td><td>SGI 4D/TFP</td><td>Irix 6</td><td>sgi,net,X11</td><td>X11</td></tr>
<tr><td>sun3</td><td>Sun-3/*</td><td>SunOS 4.1.X</td><td>net,X11</td><td>X11</td></tr>
<tr><td>sun4</td><td>Sun-4/*</td><td>SunOS 4.1.X</td><td>net,X11</td><td>X11</td></tr>
<tr><td>sun5</td><td>Sun-4/*</td><td>SunOS 5.3,5.4</td><td>net,X11</td><td>xgl,X11</td></tr>
</table>
</center>
<p>
For high-performance graphics, the SGI and Sun (GX) platforms
work best.
<p> b)
With slight modifications to the configuration files, these
additional hardware/software configurations can be easily supported.
In many cases, these differences are due to slight variations in
the hardware options installed, or the version of the software
being used.
<center><table border=1>
<tr><th>MTYPE</th><th>Hardware</th><th>Software</th></tr>
<tr></tr>
<tr><td>3d</td><td>SGI 3030</td><td>Version 3.5, 3.6</td></tr>
<tr><td>apollo</td><td>Apollo</td><td>SR10.1</td></tr>
<tr><td>ard</td><td>Stardent Titan</td><td>System V</td></tr>
<tr><td>aux</td><td>Apple Mac II</td><td>AUX 1.0</td></tr>
<tr><td>eta</td><td>ETA-10</td><td>System V</td></tr>
<tr><td>fx</td><td>Alliant FX/8, /80</td><td>Concentrix 3.0, 4.0</td></tr>
<tr><td>fy</td><td>Alliant FX/2800</td><td>Concentrix 5</td></tr>
<tr><td>ibm</td><td>RS/6000</td><td>AIX</td></tr>
<tr><td>ipsc</td><td>iPSC/860 Hypercube</td><td>NX/2</td></tr>
<tr><td>n16</td><td>Encore Multi-Max</td><td>System V</td></tr>
<tr><td>next</td><td>NeXT</td><td>NeXT 2.0</td></tr>
<tr><td>np1</td><td>Gould NP1</td><td>UTX</td></tr>
<tr><td>pyr</td><td>Pyramid 9820</td><td>OSx Version 4.1</td></tr>
<tr><td>sel</td><td>Gould PN6080, PN9080</td><td> - </td></tr>
<tr><td>stad</td><td>Stardent VISTRA</td><td>System V</td></tr>
<tr><td>stl</td><td>Stellar</td><td>System V</td></tr>
<tr><td>vax</td><td>DEC VAX-11</td><td>Berkeley 4.1 BSD</td></tr>
</table></center>
These systems are not considered ``supported'', but should work with
little or no effort.
<p> c)
Porting this software to a machine which is not
in one of the two tables above
will require some additional configuration or programming effort.
See the section on <a href="porting">SUPPORTING A NEW MACHINE</a>,
below, for details.
<P>
There are some machine/display combinations which are supported
that are not part of the default configuration.
Optional framebuffer support is:
<center><table border=1>
<tr><td>if_ab</td><td>Abekas A60 videodisk (ethernet)</td></tr>
<tr><td>if_adage</td><td>Adage RDS-3000 ("Ikonas")</td></tr>
<tr><td>if_ptty</td><td>AT&T 5620 w/special Moss layer</td></tr>
<tr><td>if_sun</td><td>SunView interface</td></tr>
<tr><td>if_ts</td><td>TekSource VME framebuffer</td></tr>
<tr><td>if_rat</td><td>Raster Technology One/80</td></tr>
<tr><td>if_remote</td><td>Network access to remote display</td></tr>
<tr><td>if_sgi</td><td>SGI Iris 3-D display</td></tr>
<tr><td>if_4d</td><td>SGI 4-D display</td></tr>
<tr><td>if_ug</td><td>Ultra Graphics</td></tr>
<tr><td>if_X</td><td>X Window System (X11R3, R4, R5)</td></tr>
</table></center>

<P>
At present, all versions of <b>mged</b> have support for these types of
display devices by default:
<center><table border=1>
<tr><td>dm-plot</td><td>any UNIX-plot filter</td></tr>
<tr><td>dm-tek</td><td>Tektronix 4014 and family</td></tr>
<tr><td>dm-tek4109</td><td>Tektronix 4109</td></tr>
<tr><td>dm-ps</td><td>PostScript</td></tr>
</table></center>
<P>
These optional display devices are also supported,
when specifically configured:
<center><table border=1>
<tr><td>dm-ir</td><td>SGI 2400, 3030</td></tr>
<tr><td>dm-4d</td><td>SGI 4-D</td></tr>
<tr><td>dm-sun</td><td>SUN 3.2 Pixwin</td></tr>
<tr><td>dm-rat</td><td>Raster Tech One/180,380</td></tr>
<tr><td>dm-rat80</td><td>Raster Tech One/80</td></tr>
<tr><td>dm-X</td><td>X Window System (X11R4, R5)</td></tr>
<tr><td>dm-xgl</td><td>SUN XGL interface</td></tr>
</table></center>
<H1>
DISK STORAGE REQUIREMENTS</H1>
<P>
The BRL-CAD Package is distributed in source code form only,
so you will need enough space to simultaneously store
the source material, documentation, binary files, and test images.
<P>
The TAR archive of the source materials requires about 48 MBytes.
You will need about 350 MBytes of free space to compile in. On an SGI
Irix 4.0.5 system, the installed /usr/brlcad tree requires 165 MBytes.
On an SGI Irix 5.2 system, the installed /usr/brlcad tree requires only
21 MBytes.  On a Sun-4 system, the installed /usr/brlcad tree requires
only 20 MBytes.  On a BSDI system, the installed /usr/brlcad tree requires
300 MBytes (not a typo).
On a DEC Alpha system, the installed /usr/brlcad tree requires 26 MBytes.
The difference is due to the availability of shared
library support in the later operating systems.
(More on shared libraries, below).
<H1>LOADING THE SOFTWARE</H1>
<ol>
<LI>
Find a disk with at least 300 Mbytes of free space that you can use.
<LI>
Mount the distribution tape on the tape drive.
Make certain that the tape is write protected.
For "round" (1/2 inch) tapes, be certain that the write-enable ring
has been removed from around the rear of the center hole.
For "square" IBM 3480-style tape cartridges, be certain that
the thumbwheel is set so that the white dot is showing.
For the DC-300 style tape cartridges,
such as are used on Sun and SGI workstations,
be certain that the
arrow in the upper left corner of the cartridge is pointing to the "SAFE"
position.
For the Exabyte 8mm style tape cartridges,
be certain that the write protect tab has been slid so that the red portion
is visible.
For the DAT 4mm style tape cartridges,
be certain that the write enable tab has been slid so that the white
portion is not visible.
<LI>
Change directory to the place where you want the source code to go, and
run these two commands:<br>
<pre><b>
	mkdir cad
	cd cad
</b></pre>
<p>
This will create a directory for containing the entire BRL-CAD Package
tree, to keep this material separate from other projects that you
may be working on.
<LI>
Extract the contents of the tape.  On a system which is based
on Berkeley UNIX, run:
<pre>
	tar x
</pre>
On a system which is based on AT&T System V UNIX, run:
<pre>
	tar xo
</pre>
to forgo System V's default (bad) behavior
of changing the ownership of the files
as they are read from the tape.
<P>
Note that if you have the tape mounted in a non-standard location,
or are using a Sun workstation, it will be necessary to
specify the tape drive to use.  For example, on Berkeley UNIX,
to use tape drive number one (mt1), run:
<pre>
	tar xf /dev/rmt1
</pre>
On a Sun workstation, you will need to use the command
<pre>
	tar xf /dev/rst8
</pre>

in order to have the Sun workstation read the tape using the industry
standard QIC-24 format, rather than the default Sun behavior of reading
the tape in QIC-11 format.
<li>
Apply all the relevant errata sheets.  They are stored on the
anonymous FTP server host ftp.brlcad.org, in the directory BRL-CAD,
and are named "errata4.0-irix4" and the like.
</ol>
<H1>
SOFTWARE ORGANIZATION</H1>
<center><table border=1>
<tr><TH>PROGRAMS</th><th>Description</th></tr>
<tr></tr>
<tr><td>rt</td><td>A ray-tracing lighting model, for rendering</td></tr>
<tr><td>mged</td><td>A solid-model editor</td></tr>
<tr><td>conv</td><td>ASCII/binary database converters</td></tr>
<tr><td>fbserv</td><td>Remote network frame-buffer server</td></tr>
<tr><td>util</td><td>Zillions of image-handling utilities and tools</td></tr>
<tr><td>vdeck</td><td>Convert mged models to GIFT-format card decks.</td></tr>
<tr><td>tools</td><td>Utah Raster Toolkit tools</td></tr>
<tr></tr>
<tr></tr>
<tr><th>LIBRARIES</th><th>Description</th></tr>
<tr></tr>
<tr><td>librt</td><td>A solid-model ray-tracing library</td></tr>
<tr><td>libspl</td><td>A B-spline library</td></tr>
<tr><td>libpkg</td><td>A "message-passing" interface to TCP network links</td></tr>
<tr><td>libfb</td><td>A generic frame-buffer library</td></tr>
<tr><td>libplot3</td><td>A public-domain 2-D and 3-D UNIX-Plot library</td></tr>
<tr><td>libtig</td><td>Some plotting routines built on libplot3</td></tr>
<tr><td>librle</td><td>A Run-Length-Encoding library (originally from UofUtah)</td></tr>
<tr><td>libmalloc</td><td>The Princeton malloc(3) -- a better malloc</td></tr>
<tr><td>libwdb</td><td>A library for procedurally writing databases</td></tr>
<tr><td>libredblack</td><td>A library implementing red-black trees</td></tr>
<tr></tr>
<tr></tr>
<tr><th>MISC</th><th>Description</th></tr>
<tr></tr>
<tr><td>papers</td><td>Full-length papers</td></tr>
<tr><td>doc</td><td>Various smaller documents of lower quality</td></tr>
<tr><td>db</td><td>Several solid-model databases, in ASCII form</td></tr>
<tr><td>bench</td><td>Scripts to drive the RT benchmark</td></tr>
<tr><td>pix</td><td>Reference images for the RT benchmark</td></tr>
<tr><td>dmdfb</td><td>libfb support for layers in Teletype 5620 DMD terminal</td></tr>
<tr><td>whetstone</td><td>FORTRAN Whetstone benchmark</td></tr>
<tr><td>dhrystone</td><td>"C" Dhrystone benchmark</td></tr>
<tr></tr>
<tr></tr>
<tr><th colspan=2>CONTRIBUTED SOFTWARE (contributed/)</th></tr>
<tr></tr>
<tr><td>cake</td><td>A Fifth Generation version of MAKE</td></tr>
<tr><td>mgm</td><td>Mged On-Line Manual</td></tr>
<tr><td>off-3d</td><td>"OFF - A 3D Object File Format" document</td></tr>
<tr><td>pbm</td><td>Portable Bitmap Toolkit</td></tr>
<tr><td>spd</td><td>"Standard" Procedural Databases</td></tr>
<tr><td>toolkit-2.0</td><td>Utah Raster Toolkit, Release 2.0</td></tr>
</table></center>

<P>
Please note that
this distribution package does <I>not</i> include the various
military-specific model
analysis tools such as GIFT, SAR, SLAVE, VAST, etc., nor does it
include any military databases.
If you desire to have access to this material, please contact
ARL.
<H1>
CONFIGURATION</H1>
<P>
If you are configuring the software for more than one type of computer,
you will have to go through this configuration procedure separately for
each kind of system.
Configuration questions apply only to the hardware available on the
particular system presently being configured.
<H2>
Normal (Single Machine) Configuration</H2>
<P>
As <b>Cakefile.defs</b> is distributed,
the default is to place the compiled object modules and final products
in the same directories as contain the source code.
This is the style of operation that most UNIX software packages
follow.
It has the advantage of being convenient and familiar.
<H2>
NFS-based Multi-Machine Configuration</H2>
<P>
If you have several types of machines sharing a single filesystem
using the Sun NFS (Network File System) or the AT&T RFS (Remote
File System),
and you wish to share a single copy of the BRL-CAD source tree
with all the remote client machines,
while maintaining separate binaries
for each different <I>type</i> of client machine,
then you probably want to take advantage of BRL-CAD's NFS-style
multi-machine support.
In this mode, a separate directory is made for each
source directory for each type of client machine.
This way, the binaries for each type of client machine can not
co-mingle, yet everything is generated from a common set of
source code.
For example, the sources in cad/librt/ would have sun3 binaries
in the directory cad/.librt.sun3/, and SGI 4-D binaries
would be located in the directory cad/.librt.4d/.
The leading dot on the binary directories keeps them ``invisible''
to <b>ls</b>(1).
<P>
This multi-machine configuration
is the strategy used at BRL, where a single fileserver
holds the master copy of the source code, and provides NFS
service for Goulds, Alliants, Crays, Convexes, Sun-3s, Sun-4s, SGI-3Ds and SGI-4Ds.
Having this capability makes it much easier to keep consistent
binaries on a wide variety of machines, and minimizes "out of phase"
errors between different members of the development group.
Having the source code and binaries in separate directories requires
slightly more care to be certain that you are in the right directory
before running <b>cake</b>,
but being able to share one set of sources across many different
kinds of machines makes this well worthwhile.
If you have only one kind of machine, don't bother.
<P>
To adopt this style of behavior,
you will need to activate the "NFS" option in <b>Cakefile.defs</b>,
by adding a <b>#define NFS 1</b> line
after the large NFS comment block, so that it reads:
<pre><b>
	#undef NFS<br>
	#define NFS 1<br>
</b></pre>
Then, further on, you will also be instructed to run <b>cake mkdir</b>
to set up the binary directories for the machine you are installing.
<P>
You will also have to update the shell script <b>gen.sh</b> to
change <b>NFS=0</b> to <b>NFS=1</b>.
<P>
Some C-shell aliases that have proven helpful for dealing with this
somewhat more complex environment are:
<pre>
# Determine machine type
test -f /usr/brlcad/bin/machinetype.sh
if ( $status == 0 )  then
	set machine=`sh /usr/brlcad/bin/machinetype.sh`
else
	set machine=unknown
endif
# Build "mcd" to push source-code dir onto dir stack, then goto binary dir
foreach i ( /n/spark/m/cad   ~/cad )
	test -d $i
	if ( $status == 0 )  then
		alias mcd "cd $i/\!:1; pushd ../.\!:1."'$machine'
		break
	endif
end
</pre>
<H2>
CAKE:  A Fifth Generation MAKE</H2>
<P>
The complexity of the NFS environment described above required a
tool for maintaining binary files that was more powerful than
the standard UNIX <b>make</b>(1) utility.
After some evaluation of the options, the <b>cake</b>(1)
utility was selected.
<b>cake</b> uses PROLOG-style pattern matching and resolution,
rather than the suffix-to-suffix translation of <b>make</b>,
making it far more general.
<b>cake</b> also uses the C-PreProcessor (/lib/cpp) to provide
a general macro, conditional code, and file inclusion facility.
However, for all these differences, the actual <b>Cakefile</b> files
that you will find in the various source directories will look
similar enough to <b>Makefile</b> files that all but the most
extensive configuration changes can be attempted without having
to learn much about <b>cake</b>.
<H1>
INSTALLATION DIRECTORIES</H1>
<P>
At this stage, it is necessary to decide
what UNIX directory the BRL-CAD Package
executable programs are going to be installed in, and to make certain
that the binary (program) installation directory is in your Shell
search path.
This is necessary because certain programs (such as the <b>cake</b> program)
and some Shell scripts (such as <b>machinetype.sh</b>) need
to be placed in a location generally accessible to you, before
the BRL-CAD sources can be compiled.
<P>
A full production installation done with <b>cake install</b>
will require five directories for installing the compiled software in.
These directories are known symbolically as BINDIR, LIBDIR, ETCDIR, MANDIR, and INCDIR.
BINDIR is where executable ("binary") programs and scripts are installed,
LIBDIR is where all the libraries are installed, for you to use when
writing additional software for this environment, and
ETCDIR is where a few additional ("etc") programs,
such as network server daemons,
are installed.
MANDIR is where the manual page subdirectories are installed.
INCDIR is where all the include files are installed,
so that programs which you write can reference them.
<P>
In all cases, it is necessary for the BINDIR string to be in your
search path, before the BRL-CAD software can be set up.
<H2>
INSTALLATION DIRECTORIES \(em BENCHMARKING or EXPLORATION USE</H2>
<P>
For benchmark use, and for exploratory use, the binary directory should
probably be set to some directory beneath your home directory.
Note that the traditional UNIX
style is to name a personal directory for binary programs "bin",
but you can substitute any name here, if you prefer.
If you don't have some kind of "bin" directory yet, run:
<pre><b>
	cd		# Go to your HOME directory
	mkdir bin
	cd bin
	pwd
	cd
</b></pre>
For this example, assume that the path to your "bin"
directory (as printed by <b>pwd</b> above)
was "/a/d/mike/bin".
Use this path string as BINDIR.
<P>
Using the <I>full</i> path name of your "bin" directory,
update the definitions for BINDIR,
LIBDIR, MANDIR, INCDIR, and ETCDIR in the files "Cakefile.defs", "setup.sh",
"cray.sh", "cake/Makefile", "cakeaux/Makefile",
"brlman/awf", and "brlman/brlman".
The shell script "newbindir.sh" can be used to simplify this process
for you, if BINDIR, LIBDIR, MANDIR, INCDIR, and ETCDIR are all
subdirectories with the same parent directory.  Just run it with the
first argument being the full path name of the new parent directory.
<H2>
INSTALLATION DIRECTORIES \(em PRODUCTION USE</H2>
<P>
For production use, the software comes configured to install
everything in the directories "/usr/brlcad/bin", "/usr/brlcad/lib",
and "/usr/brlcad/etc".
If this choice is acceptable to you, then first you need
to make these directories, or have a superuser make them for you:
<pre><b>
	mkdir /usr/brlcad<br>
	cd /usr/brlcad<br>
	mkdir bin lib etc include man vfont<br>
	mkdir man/man1 man/man3 man/man5<br>
	chmod 775 * */*<br>
	chown YOURNAME * */*<br>
</b></pre>
where you replace "YOURNAME" with your user name, and then
you need to add "/usr/brlcad/bin" to your search path.
See the previous section for instructions on how to do this.
<P>
If you wish to install the software somewhere else, create your "bin",
"lib", and "etc" directories, and
update the definitions for BINDIR,
LIBDIR, and ETCDIR in the files "Cakefile.defs", "setup.sh",
"cray.sh", "cake/Makefile", and "cakeaux/Makefile".
Then, add your choice for BINDIR to your search path.
Note that the script "newbindir.sh", as described above, will
update the required files for you, if the BINDIR, LIBDIR, MANDIR, INCDIR,
and ETCDIR all have the same parent directory.
<P>
Running setup.sh will cause all the necessary directories to be
created.
<H2>Updating Your Search Path</H2>
<dl>
<dt><b>Bourne Shell (/bin/sh)</b>
<dd>
If you are a Bourne Shell user (/bin/sh,
generally the default shell on most systems),
you will need to edit your ".profile" file, and modify the PATH
variable to include the full path name of your "bin" directory (BINDIR).
In the editor, look for a line that looks something like:
<pre>
	PATH=/usr/ucb:/bin:/usr/bin:/usr/local/bin::
</pre>
and add the path name of your "bin" directory after the equals ("=") sign.
In this example, the new form would look like one of the two lines
below;  the first line is the example non-production form, and
the second line is the production form.
<pre>
	PATH=/a/d/mike/bin:/usr/ucb:/bin:/usr/bin:/usr/local/bin::

	PATH=/usr/brlcad/bin:/usr/ucb:/bin:/usr/bin:/usr/local/bin::
</pre>
where the full path name for the "bin" directory has been added to the
front of your PATH specification.
Then, you must run:
<pre>
	.   .profile
</pre>
(dot space dot-profile) to have the Shell set up your new PATH specification.
<dt><b>C-Shell (/bin/csh)</b>
<dd>
If you are a C-Shell user (/bin/csh), you will need to edit your ".cshrc"
file, and modify the "set path" directive to include the full path name of
your "bin" directory.
In the editor, look for a line that looks something like:
<pre>
	set path=(/usr/ucb /bin /usr/bin /usr/local/bin .)
</pre>
and add the path name of your "bin" directory after the open paren ("("),
followed by a space.
In this example, the new form would look like one of the two lines
below;  the first line is the example non-production form, and
the second line is the production form.
<pre>
	set path=(/a/d/mike/bin /usr/ucb /bin /usr/bin /usr/local/bin  .)

	set path=(/usr/brlcad/bin /usr/ucb /bin /usr/bin /usr/local/bin  .)
</pre>
where the full path name for the "bin" directory has been added to the
front of your search path.  Then, you must run:
<pre>
	source   .cshrc
</pre>
to have this change take effect.
</dl>
<H1>
ONE-TIME SETUP</H1>
<P>
At this point, it is important to check the
automatic determination of your machine type and system parameters,
by running:
<pre>
	sh machinetype.sh -v
</pre>
Be certain that the values which are printed are reasonable.
First, make sure that the MACHINE variable is appropriate
for your machine; see the table of supported machine types, above.
If the MACHINE variable is set properly,
the UNIXTYPE variable should also be set properly:  "BSD" for systems
based on the Berkeley version of UNIX, "SYSV" for systems based
on AT&T SystemV.
Finally, the HAS_TCP variable should be one ("1") if your machine
supports the TCP/IP network protocols, and zero ("0") otherwise.
If any of these parameters are not correct,
see the section on
<a href="porting">SUPPORTING A NEW MACHINE</a>, below.
<P>
Now that the installation directories have been made, and the
binary directory has been added to your search path,
the next step is to run the "setup.sh" shell script
from within the "cad" directory:
<pre>
	sh setup.sh
</pre>
This script first checks to make sure that your choice for BINDIR
has been correctly installed into your search path and exported.
Next, it installs several shell scripts (including <b>machinetype.sh</b>)
into BINDIR.
Finally, it compiles <b>cake</b> and <b>cakeaux</b>.
<P>
Once this is complete, if you use <b>csh</b> for your login shell,
(or a derivative of <b>csh</b>, such as <b>tcsh</b>), run:
<pre>
	rehash
</pre>
to get these additional programs into your shell's hash table.
Bourne shell (<b>sh</b>) and Korn shell (<b>ksh</b>) users should skip
this step.
<P>
Only if you elected the NFS-style multi-machine support above
and edited <b>Cakefile.defs</b>, you need to run
<pre>
	cake mkdir
</pre>
at this point, to make the binary directories for this machine.
This step will need to be repeated while logged into each different
kind of machine that you will be supporting via NFS.
<H1>
COMPILING AND RUNNING THE BENCHMARK</H1>
<P>
To compile just enough of the BRL-CAD software to run the benchmark,
and then to conduct the actual benchmark test, run:
<pre>
	cake benchmark

	cd bench

	sh run.sh
</pre>
The <b>cake benchmark</b> will process just the directories
that are needed to run the benchmark:
libmalloc, conv, db, libpkg (if HAS_TCP==1),
libfb, libplot3, libspl, librt, rt.
If any fatal errors occur during this process,
consult the section on <a href="porting">SUPPORTING A NEW MACHINE</a>.
<P>
Running the benchmark takes several hours on a DEC VAX-11/780 machine,
so scale your expectations accordingly.
For details on
the background of the benchmark,
the BRL-CAD Benchmark Test Methodology,
the Ray-Tracing Figure of Merit (RTFM) used to judge the
computational performance of different computer systems,
and for data on the measured performance of various machines, please
consult the document in "doc/benchmark.doc".
<H2>
Obtaining Correct Results</H2>
<P>
The benchmark timings are not considered valid unless
the correct results are given.
Make sure that the answers match the reference files
to within plus-or-minus one in each color (see pixdiff(1)).
You may wish to
compare the execution times and log file remarks
from your tests (in the "bench/xxx.log" files) with the
VAX-11/780 (with hardware FPA) times which are given in the
"pix/xxx.log" files.
The reference images are also located in the "pix/" directory.
<P>
For example,
if you are running the benchmark on a Cray X-MP, as I'm sure all of you
are,
moss.pix will have 152554 pixels off by 1,
world.pix will have two pixels off by 1,
and m35.pix will have 75 pixels off by 1.
This is not to be considered an error, as it is a consequence of
differences arising from Cray's different hardware floating point format,
division algorithm, and rounding rules.
<H1>
GENERAL STRUCTURE OF THE SOFTWARE</H1>
<P>
In the top level directory (<b>cad</b>),
a dummy Makefile and Cakefile exist, both of which simply invoke the
Shell script <b>gen.sh</b> with their argument.
<b>gen.sh</b> is used to control the processing of all commonly used
operations, to see that operations are performed on the proper set of
directories.
<P>
The operations supported by <b>gen.sh</b> are:
<center><table border=1>
<tr><th>Keyword</th><th>Description</th></tr>
<tr><td></td></tr>
<tr><td>benchmark</td><td>Special:  Make only benchmark</td></tr>
<tr><td>all</td><td>Makes all software</td></tr>
<tr><td>clean</td><td>rm *.o, leave products</td></tr>
<tr><td>noprod</td><td>rm products, leave *.o</td></tr>
<tr><td>clobber</td><td>rm products and *.o</td></tr>
<tr><td>lint</td><td>run lint</td></tr>
<tr><td>install</td><td>install all products</td></tr>
<tr><td>uninstall</td><td>remove all products</td></tr>
<tr><td>print</td><td>print all sources to stdout</td></tr>
<tr><td>typeset</td><td>troff all manual pages</td></tr>
<tr><td>nroff</td><td>nroff all manual pages</td></tr>
<tr><td>mkdir</td><td>NFS: create binary dirs</td></tr>
<tr><td>relink</td><td>NFS: relink Cakefile</td></tr>
<tr><td>rmdir</td><td>NFS: remove binary dirs</td></tr>
</table></center>

<P>
Within each directory is a <b>Cakefile</b> that includes
<b>../Cakefile.defs</b>, either
<b>../Cakefile.lib</b> (if the directory makes a library) or
<b>../Cakefile.prog</b> (if the directory makes programs),
and finally <b>../Cakefile.rules</b>.
This structure allows all configuration of this package to be
concentrated in the single file <b>Cakefile.defs</b>,
with per-product structural information in the individual
<b>Cakefile</b>s located in each sub-directory.
<b>Cakefile.rules</b> contains all the rules which are used to
implement the ancillary operations (such as "typeset", "install", etc.),
and these rules then apply uniformly in all product directories.
While this complex structure may seem overwhelming at first,
once established, it makes the task of configuration very simple.
<H1>
COMPILING THE FULL PACKAGE</H1>
<P>
To compile the full BRL-CAD Package on a supported configuration,
sit in the top ("cad") directory, and run:
<pre>
	cake all

	cake install
</pre>
Note that if the products from a previous installation remain
in INSTDIR (e.g., "/usr/brlcad/bin", etc.), then the install operation
very carefully renames each existing product as product.bak before
installing the new product.
For example, an existing version of mged would be renamed
/usr/brlcad/bin/mged.bak before the new version is installed
as /usr/brlcad/bin/mged.
If this behavior is not desired, perhaps because of limited disk space,
the rule "cake install-nobak" can be used instead.
<H2>
Installing Network Framebuffer Service</H2>
<P>
If your system reported HAS_TCP=1, then you have TCP/IP networking,
and you have the option of
offering in-bound remote framebuffer service via
<b>fbserv</b>, the framebuffer server and remote-framebuffer daemon.
(Note that in previous releases, this function was provided by <b>rfbd</b>.
If you wish to do this, you should be sure that
the IF_REMOTE capability has been selected for <b>libfb</b>.
(In the supported configurations, it is).
<P>
To define the service,
add this line to /etc/services:
<pre>
remotefb     5558/tcp       # BRL Remote Frame Buffer
</pre>
<P>
If your system does not support <b>inetd</b>(8),
<b>fbserv</b> should be started in /etc/rc.local.
If your system uses the Sun style of <b>inetd</b>(8),
<b>fbserv</b> must be started with this /etc/servers entry:
<pre>
remotefb tcp    /usr/brlcad/bin/fbserv
</pre>
<P>
If your system supports the Berkeley 4.3 BSD style of <b>inetd</b>(8),
<b>fbserv</b> must be started with this /etc/inetd.conf entry:
<pre>
remotefb stream tcp     nowait  nobody  /usr/brlcad/bin/fbserv       fbserv
</pre>
This entry depends on having a ``nobody'' user, so be certain that your
/etc/passwd file contains a line like this.  (The choice of UID and
GID of -2 is intentional):
<pre>
nobody:*:-2:-2:NFS Unprivileged user:/nonexistent:/dev/null
</pre>
<H2>
Special Kernel/Shared Memory Considerations on all SGI systems</H2>
<P>
When using the framebuffer library on an SGI system,
it is necessary to modify
certain kernel limits in the binary image of your kernel to be able to
use a large block of shared memory.
<P>
For an SGI 3D,
follow the directions in
libfb/if_sgi.c, and then reboot your workstation to allow the changes to
take effect.  There are claims that on some SGI 3-D machines with only
4 Mbytes of memory, this may
cause unreliable operation, so be certain to keep a backup kernel.
<P>
For an SGI 4D, software release 3.0 and up, add these entries
to your kernel configuration:
<pre>
	#define SHMMAX (MAXUMEM*NBPP)
	#define SHMMIN 1
	#define SHMMNI 100
	#define SHMSEG 6
	#define SHMALL 4000
</pre>
then install the new kernel, and reboot.
<H1>
<a name="porting">SUPPORTING A NEW MACHINE</a></H1>
<P>
This rather lengthy section attempts to document
how to add support for a new type of machine.
It may also prove useful to study this material if
you experience difficulties with one of the existing configurations.
<H2>
machinetype.sh</H2>
<P>
The first step is enhancing <b>machinetype.sh</b> and <b>Cakefile.defs</b>
to recognize the type of machine that you are using.
Both of these files use the same technique:
they directly run the C Preprocessor (/lib/cpp) and
test for the existence of a vendor-specific pre-defined symbol that
identifies the machine type,
using C <b>#ifdef</b> constructions.
For example, on a DEC VAX, the test <b>#ifdef vax</b> is true,
while on an Alliant, the test <b>#ifdef alliant</b> is true.
The documentation for the C Compiler <b>cc</b>(1)
will often mention the vendor-specific symbol to test for.
If not, a little playful experimentation with the vendor's name
and the machine model name/number will usually suffice.
Sometimes two symbols need to be checked
to tell certain incompatible models apart.
For example, on the SGI machines,
both "sgi" and "mips" need to be checked.
If defined(sgi) and !defined(mips), then it is a 3030,
if defined(sgi) and defined(mips), then it is a 4D.
Sometimes it is worse than that.
<P>
Update <b>machinetype.sh</b> first;  it is easier to experiment with
than the full <b>Cakefile.defs</b> file.
The code that will need to be added will be of the form:
<pre>
	#ifdef eta10
	/*	ETA-10 running UNIX System V. */
	#	undef	eta
		MACHINE=eta;
		UNIXTYPE=SYSV;
		HAS_TCP=0;
	#endif
</pre>
All systems have a small block of code that will look much like the example
above.
Your first task is to select a "nickname" for the machine that is
four characters long, or shorter, in the MACHINE= line.
In the example case of the ETA-10, the string "eta10" was shortened to "eta".
Note the <b>#undef eta</b> to ensure that the "nickname" is not also a
C Preprocessor builtin symbol.
In the UNIXTYPE= line, only two choices are currently valid,
"SYSV" for variants of AT&T System V, and "BSD" for Berkeley UNIX 4.2 BSD
and 4.3 BSD.
Finally, if the machine supports the TCP network protocols
using the Berkeley <I>socket</i> interface, then define
HAS_TCP=1, otherwise define HAS_TCP=0.
Extending the network support for non-TCP environments,
or TCP implementations that use some other interface,
will probably only require changes to <b>libfb</b>(3)
and <b>fbserv</b>(1),
and will not be elaborated on here.
Check how you did by running:
<pre>
	sh machinetype.sh -v
</pre>
and making any necessary corrections.
<P>
If <b>machinetype.sh</b> reports that HAS_TCP=0, i.e.,
this is a machine without TCP network capability,
the <b>gen.sh</b> script will automatically delete
<b>fbserv</b> and <b>libpkg</b> from the PRODUCTS list,
as they serve no purpose in a non-networked environment.
<H2>
Cakefile.defs</H2>
<P>
The file <b>Cakefile.defs</b> is included in every local <b>Cakefile</b>,
and contains the common definitions
and configuration information
for the BRL-CAD Package.
There are a great many symbols which may be defined
to specify the details of the desired configuration.
<H3>
Machine Type Information</H3>
<P>
Edit the file <b>Cakefile.defs</b> and
start by making the same general kind of additions as were done
for <b>machinetype.sh</b>.
When porting the BRL-CAD software to a new machine,
it is wise to start with a configuration that does not
attempt to use the network, and which does not try to access any
display hardware.
Once all the basic software compiles, and the benchmark produces correct
results, then a <b>cake clobber</b> can be done,
the configuration edited to add more complexity,
and a full <b>cake all</b> can be run.
<P>
As an example which tracks the example in the previous section,
the additions to support the ETA-10 are simply:
<pre>
	#ifdef eta10
	#	undef	eta
	#	define	MTYPE	eta
	#	define	UNIXTYPE	SYSV
	#	define	HAS_TCP        0
	#	define	LIBRT_TIMER    timerunix
	#endif
</pre>
The values for MTYPE, UNIXTYPE, and HAS_TCP should match those
values placed in <b>machinetype.sh</b>.
This definition for the ETA-10 will build a package with minimal
graphics display support, and no network support.
<P>
The timer configuration LIBRT_TIMER must be specified, based on the
version of UNIX you are using. This timer module is for providing CPU
and elapsed time indications.  If your system has a vendor-specific clock
with more resolution than the normal UNIX library provides, you should
eventually create your own system-specific timerXXX.c module,
although timerunix.c is a fine starting point for any UNIX system.
The full range of choices for LIBRT_TIMER are:
<center><table border=1>
<tr><td>timerunix</td><td>Generic UNIX</td></tr>
<tr><td>timer42</td><td>4.2 BSD, 4.3 BSD (Berkeley UNIX)</td></tr>
<tr><td>timercos</td><td>Cray X-MP running COS</td></tr>
<tr><td>timer52brl</td><td>For BRL's System 5-under-4.n BSD</td></tr>
<tr><td>timerhep</td><td>Denelcor HEP</td></tr>
</table></center>

<H3>
C Compiler Configuration</H3>
<P>
The symbols CC, CC_DEFS, and CC_OPTS can be set to
define various features used with the C compiler.
CC is the full path to the C compiler,
CC_OPTS is used to select the most appropriate kind of optimization
for this configuration, and
CC_DEFS is used to pass definitions to the compiler.
For example, if the C compiler can not support "void" functions,
this can be bypassed with:
<pre>
	#	define	CC_DEFS	-Dvoid=int
</pre>
If the compiler needs a special optimization switch,
this can be done with something like this:
<pre>
	#	define	CC_OPTS	-f68881
</pre>
For most systems, the default values should be fine.
Changing the definition of CC can be useful when testing a new release
of the C compiler.  The BRL-CAD Package is used by several hardware vendors
as part of their standard compiler regression test suite.
<H3>
FORTRAN Compiler Configuration</H3>
<P>
The full path to the FORTRAN compiler is specified in the symbol FC.
The default value is /usr/bin/f77.
Note that there is no longer a single line of FORTRAN code in
the BRL-CAD Package, but the Cakefiles still support it,
as a little user-developed code is still in FORTRAN.
<H3>
Host Name</H3>
<P>
The program to run to obtain the name of the current host is
specified by the symbol GETHOST.
If this symbol is not defined, the appropriate default is
chosen based on BSD or SYSV with this code:
<pre>
#if	!defined(GETHOST)
#	if	UNIXTYPE == BSD
#		define	GETHOST	hostname
#	else
#		define	GETHOST	uname -n
#	endif
#endif
</pre>
<H3>
Library post-processing (ranlib)</H3>
<P>
The program to run to properly post-process an archive which is
intended to be a subroutine library is specified by the symbol RANLIB.
The default values are chosen with the code below.
Note that on older System V release, no post-processing is possible,
so the command <b>echo</b> is substituted.
<pre>
#if	!defined(RANLIB)
#	if	UNIXTYPE == BSD
#		define	RANLIB	ranlib
#	else
#		define	RANLIB	ranlib5.sh
#	endif
#endif
</pre>
<H3>
libfb configuration</H3>
<P>
The configuration for the framebuffer library is specified
by the two symbols LIBFB_CONFIG, LIBFB_OBJS.
If these two symbols are not defined in the configuration that you
provide, then they will be defaulted using this code:
<pre>
#if !defined(LIBFB_OBJS) || !defined(LIBFB_CONFIG)
#	if HAS_TCP == 0
#		define	LIBFB_OBJS	if_ptty
#		define	LIBFB_CONFIG	-DIF_PTTY
#	else
#		define	LIBFB_OBJS	if_remote pkg if_ptty
#		define	LIBFB_CONFIG	-DIF_REMOTE -DIF_PTTY
#	endif
#endif
</pre>
If this is a TCP-capable system,
the defaults provide for including the "remote" network framebuffer
capability, in addition to the terminal-line AT&T 5620 "ptty" interface.
The LIBFB_OBJS symbol is given the base name of all the object modules
to be included, and the LIBFB_CONFIG symbol is given all the C compiler
definitions necessary to incorporate the <b>extern</b> linkages to
the desired object modules, via the array in libfb/fb_generic.c.
<P>
Even if your configuration has no display hardware specified,
this library is necessary, as the debug and disk-file interfaces are
always useful.
Lacking any displays at all, you may be able to utilize
the bw-impress(1) program to produce pictures on an Imagen
laser-printer, or bw-px(1) to produce a PostScript image.
<P>
The philosophy of <b>libfb</b> is that it is a fully self-contained
library.
An applications program that desires to have framebuffer support
need only link with <b>libfb</b>, and all subroutines that may be
needed on that machine will be provided.
Frequently, this means that <b>libfb</b> will have to include
object modules drawn from one or more vendor-specific libraries,
as well as the object modules from the BRL-CAD source files.
If the symbol LIBFB_SETUP is defined, then libfb/Cakefile will
run that string as a Shell command before creating the <b>libfb</b> archive.
This is used to add object modules from vendor-specific libraries.
For an example of how this is used, see the SGI or Cray configurations.
<P>
For example, to configure a system to support the Raster Technology
display attached to a parallel port,
these lines would be added to the system-specific configuration:
<pre>
#	define	LIBFB_CONFIG	-DIF_RAT
#	define	LIBFB_OBJS	if_rat
</pre>
No vendor-specific library is required for the Raster Technology support.
<P>
As another example, for
a SUN system of release 3.2 or higher,
configuring both the display and also the network framebuffer capability
(since all SUN systems support TCP/IP networking),
these definitions would be used.
This is taken directly from Cakefile.defs:
<pre>
#	define	LIBFB_OBJS	if_remote if_ab if_sun
#	define	LIBFB_CONFIG	-DIF_REMOTE -DIF_AB -DIF_SUN
#	define	LIBFB_LIBES	LIBPKG -lsuntool -lsunwindow -lpixrect
</pre>
The first important thing to note is that when adding support for
the network "remote" framebuffer capability,
"if_remote" is listed as an object file,
and "LIBPKG" is added to the library list
for the network interface routines.
Also note that the definition of LIBFB_LIBES
mentions three SUN-specific libraries that will also be used when
building applications that use LIBFB.
<P>
As a final example, configuring a machine to use the
X Window System (X11) as a framebuffer might use these definitions:
<pre>
#	define  LIBFB_OBJS      if_remote if_X
#	define  LIBFB_CONFIG    -DIF_REMOTE -DIF_X -I/usr/local/include/X11
#	define	LIBFB_LIBES	LIBPKG -L/usr/local/lib/X11 -lX11
</pre>
Note how the X11 include directory may need to be added to LIBFB_CONFIG,
and the location of the X11 library may need to be indicated with a "-L"
flag in LIBFB_LIBES.
<P>
If you change the configuration of libfb
partway through building the system, be certain to run
<pre>
	cd libfb
	cake clobber
	cake
</pre>
before recompiling other programs, because the
external symbols compiled into the binaries
change based on the configuration options in
<b>Cakefile.defs</b>.
<H2>
mged Configuration</H2>
<P>
All versions of <b>mged</b> have support for
the four display devices listed at the beginning of this document.
If the symbols MGED_CONFIG, MGED_OBJS, and MGED_LIBES are not
defined, then a version of <b>mged</b> will be built that contains
only the standard display handlers.
In addition, a variety of optional display devices are also supported;
the list also appears at the beginning of this document.
<P>
For example, to configure an SGI Iris 3-D ("ir")
running version 3.5 of the software, with XNS networking, specify:
<pre>
#	define	MGED_CONFIG	-DDM_IR  -DNOBLOCK
#	define	MGED_OBJS	dm-ir
#	define	MGED_LIBES	-lbsd -lgl2
</pre>
Note the
necessary vendor-supplied libraries must be listed on the MGED_LIBES line.
<H2>
h/machine.h</H2>
<P>
The file "h/machine.h" has a number of configuration
options, including the setting of:
<center><table border=1>
<tr><td>fastf_t</td><td>fastest "C" floating point type (<b>float</b> or <b>double</b>)</td></tr>
<tr><td>PARALLEL</td><td>Defined for parallel processors.</td></tr>
</table></center>

VAX, GOULD, Cray, Alliant and HEP examples are provided. The defaults
should be correct for reasonable 32-bit serial computers.  Note that
K&R ``C'' specifies that all floating point calculations must be done
as <b>double</b>, so it is usually fastest to set fastf_t to
<b>double</b>. Also note that when fastf_t is <b>float</b> in 32-bit IEEE
or IBM style floating point, not enough accuracy is carried to correctly
process large models. See the "Silicon Graphics Warnings" section for
more information.
<H2>
h/rle.h</H2>
<P>
The file h/rle.h
has #<b>if</b> statements that will need modification if
your machine is a "Little-Endian" machine and your machine is not
a VAX.  "Big-Endian" machines will work without modification.
A Big-Endian machine has byte [0] on the left of the word, like IBM,
while a Little-Endian machine has byte [0] on the right side of the word,
like DEC.
<H2>
libplot3/htond.c</H2>
<P>
This routine converts between the native machine floating point format,
and IEEE double precision floating point.
This is especially important for generating binary portable plot
metafiles.
If the machine that you are porting to implements one of the
already supported native types, all you need to do is adjust
the <b>#if</b> directives for the symbol NATURAL_IEEE
to include your machine type.
(Please notify ARL when you do this, so that we can update the
master copy).
<P>
If it seems that your machine uses a novel internal floating point
format, you may have to write some code to perform the conversion.
Before undertaking such an effort, please read the file
"papers/dist-graphics", <I>Workstations, Networking, Distributed
Graphics, and Parallel Processing</i>, where this whole issue
is discussed in great detail.
You may also wish to contact ARL via E-mail to see
whether support for your machine has already been accomplished by others.
<H2>
Adding Support For New Displays</H2>
<P>
If you desire to add support for a new display, there are only two
modules that you will have to create.  The first will be for the
framebuffer library (see <b>libfb</b>(3) for more details).  A template for
creating interfaces to new devices is provided as libfb/if_TEMPLATE.c.
The second module needed is an <b>mged</b> display manager, like mged/dm-XX.c.
Here, the task is somewhat harder, as two major modes of behavior are
supported:  displaylist and refresh.  You should examine display
managers for devices similar to yours, and proceed from there.
ARL would be most interested in obtaining any additional display modules
that you might develop, should you wish to share them.
<H2>
Potential Optimizations</H2>
<P>
After initial testing, you may wish to go back and enable the special
assembler version of sqrt(), by uncommenting and editing the FAST_SQRT
line in "librt/Makefile.loc".  4.2BSD VAX and Gould UTX 1.2 versions
are provided.  Note that the 4.3BSD VAX library sqrt() is even faster
than this one by more than 40%.
<p>
The file "h/vmath.h" has macros for numerous common vector operations;
if your system has hardware support for vector operations, after getting
the program working you would profit greatly from changing these macros
to machine-specific code.
If you do this, please submit the "rays/sec" figures for the
original as well as the optimized runs.
<p>
ARL is currently
working with compilers that detect implicit vectorization.
The full results of this work will be included in a subsequent release.
<H1>
DIFFICULTIES</H1>
<P>
If you are experiencing difficulty with one of the provided
configurations, <b>Cakefile.defs</b> is the most important file
to scrutinize.
See <a href="porting">SUPPORTING A NEW MACHINE</a>.
<H2>
Extreme difficulty with libfb</H2>
<P>
In the case of extreme difficulty, a no-op stub version of libfb
is provided in rt/libfb-dummy.c.
This can be substituted for "libfb.a" in order to run the <b>rt</b>
benchmark.
<H2>
Changing Configurations of libfb, mged, librt</H2>
<P>
For <b>libfb</b>, <b>mged</b>,
and <b>librt</b>,
it is also necessary to run "<b>cake clean</b>" in those directories
after making related changes to <b>Cakefile</b> or <b>../Cakefile.defs</b>,
because the compiled binaries
of some modules depend on configuration options selected in the Cakefiles.
Failure to do this is the single most common cause of difficulty
when experimenting with the configuration of this software.
To be ultra conservative,
after each major change of a configuration file,
it would be wise to run <b>cake clobber</b> in the top directory,
and then recompile.
<H1>
LIVING WITH SHARED LIBRARIES</H1>
<P>
Many modern versions of UNIX offer shared libraries, and
this BRL-CAD release takes advantage of them on the Sun and SGI platforms.
For BRL-CAD modelers, shared libraries save a lot of disk space
and represent only a minute performance loss.
For BRL-CAD developers who are making changes to the libraries,
shared libraries offer an additional detail to keep track of.
In particular, when a new shared library is installed, all the
programs will start using it the next time they are run, even
without being explicitly recompiled.  If data structures in raytrace.h
were changed, this could be disastrous.
There are several different ways developers can cope with this:
<ol>
<li>
Disable shared library support in Cakefile.defs, and run
<pre>
	cake clobber

	cake install
</pre>
to build non-shared libraries and programs.
<li>
In /usr/brlcad/lib, make symlinks from your_source_dir/librt/librt.so to
/usr/brlcad/lib, e.g.:
<pre>
	cd /usr/brlcad/lib

	ln -s your_source_dir/librt/librt.so .
</pre>
for each of the libraries that you plan to be working on.
Note that this makes the system "installed" version of the library
your development copy.  This is only a reasonable policy if
the developer(s) are the only users of this particular machine.
<li>
On SunOS 4 machines <I>only</i>, the development tree executables
are able to find the development tree libraries automatically.
E.g. your_source_dir/rt/rt will automatically attempt to use ../librt/librt.so
before resorting to the installed version in /usr/irlcad/lib/librt.so.
Sadly, this feature does not work on SunOS 5 and SGI platforms.
<li>
You can attempt to play games with your environment variable
LD_LIBRARY_PATH, to control which library versions you are using.
</ol>
<H1>
KNOWN PROBLEMS</H1>
<H2>
CAKE Warning Message</H2>
<P>
Occasionally, CAKE will print the message
<pre>
NOTE:  Null action skipped
</pre>
This warning message is not harmful, and may safely be ignored.
<H2>
System V Documenters Workbench Unbundled</H2>
<P>
In recent releases of System V, DWB has been unbundled.
This means that for these systems, the
<b>man</b> command no longer runs <b>nroff</b> to typeset
the manual pages as they are needed.
As a result, a new strategy is employed for installing manual pages.
They now go in INSTDIR/man/man1, man3, and man5,
rather than into the system's manual directories.
At a minimum, this means that your users will have to add /usr/brlcad/man
to their MANPATH environment variable.
<P>
If your <b>man</b> command does not honor the MANPATH variable,
or your system does not have DWB installed, then you can always fall back
to using the <b>brlman</b> command.
A replacement for <b>nroff</b> known as <b>awf</b> is provided,
and is used as the basis for the <b>brlman</b> command (which is just
a shell script).
<b>awf</b> is the Amazingly Workable Formatter,
kindly provided by Henry Spencer at U of Toronto Zoology,
<henry@zoo.toronto.edu>.
In this way, all systems can have nicely formatted manual pages online,
while leaving the sources for the manual pages in <b>nroff</b> format.
<H2>
DEC VAX, 4.1 BSD and DEC Ultrix</H2>
<P>
The C compiler on 4.1 BSD UNIX systems, and on DEC Ultrix systems
is unable to handle pointers to functions which return <b>void</b>.
In the section of <b>Cakefile.defs</b> for the VAX, it is necessary
to uncomment this definition,
which maps all <b>void</b> objects to <b>int</b> objects, a harmless
workaround:
<pre>
	#	define	CC_DEFS	-Dvoid=int
</pre>
<H2>
SILICON GRAPHICS 3-D WARNINGS</H2>
<P>
The SGI IRIS workstations in
the 2400, 2400 Turbo, or 3000 series have been affectionately
nicknamed the "3D" machines, since they came before the newer "4D" machines.
<P>
If you are attempting to run the benchmarks, beware of the
<b>long float</b> -vs- <b>double</b> controversy.  The SGI C compiler
converts both <b>float</b> and <b>double</b> to 32-bit single-precision
numbers.
While the current release of <b>librt</b> is believed to generally
operate correctly in spite of this, beware of the <b>rt</b> program failing to
find roots, or being unable to perform a "box push". Unfortunately, the
"star.pix" <b>rt</b> benchmark will fail due to lack of floating point
precision, and generate lots of diagnostics, filling your disk.
<P>
SGI 3-D software release version 3.3.1, 3.4, and 3.5 have a defective
library version of hypot();  be aware of the (slower) substitute in
"rt/machine.c".
<P>
Operations of the form "*fp += incr;" are known to compile incorrectly
on SGI 3-D release 3.5 when "fp" is declared as "<b>register double</b> *fp"
(or <b>register float</b>).  The one known instance of this in
util/bwmod.c has been "fixed" with a #<b>ifdef</b> sgi.
<P>
When running MGED on a 3.5 Iris with XNS networking, there is no
select() capability, so non-blocking I/O has to be used instead.
This has two undesirable side effects.  First, it puts MGED into
a hard loop polling the workstation keyboard.  Second, it seems to
have an interaction with control-S/control-Q flow control -- if you
suspend output, most of it will be discarded.  However, MGED is
still somewhat usable in this configuration.
<P>
On an SGI 3-D, warning messages from the compiler of the form:
<pre>
"../h/rle.h", line 88: warning: field 'opcode' - bitfields are inherently unsigned.
"../h/rle.h", line 88: warning: field 'datum' - bitfields are inherently unsigned.
</pre>
may safely be ignored.
<P>
Under SGI Release 3.5, the invocation of the <b>sort</b> command
that is used to build the font table for the program <b>tools/rleClock</b>
is not handled properly, resulting in a bad input file and compiler
errors.  You can safely do without this program.
<P>
As a helpful hint,
it is very useful to add a "gclear" account to each SGI 3-D system,
so that after
using the screen in 24-bit mode when not logged into the console,
you can regain control of the screen by
typing "gclear".
By having a "gclear" account, typing "gclear" will always succeed
whether or not you are logged in.  Add this line
to /etc/passwd:
<pre>
gclear::4:5::/tmp:/usr/bin/gclear
</pre>
<P>
Currently there are no good solutions to these problems.  Voice your
opinions to the vendor.
<H2>
SILICON GRAPHICS 4-D WARNINGS</H2>
<P>
There is utterly no support for SGI 4-D machines running SGI software
releases earlier than 4.0 \(em they don't work well.
Similarly, IRIX 6.0 had not been released at the time BRL-CAD Release 4.4
was being finalized, so it is unclear how well this combination will work.
Contact ARL for an errata sheet when IRIX 6.0 is available.
<H3>
SGI IRIX 4.0.5</H3>
<P>
When compiling on IRIX 4.0.5, the module <b>librt/machine.c</b>
trips over an SGI C compiler bug, producing the following warning:
<pre>
/usr/bin/cc -G 9 -ansiposix -DIRIX=4 -O2 -I''../h -DSYSV -c ../librt/machine.c

accom: Warning 182: ../librt/machine.c, line 297: void * and function pointers are not convertible to each other

        void    (*func)() = (void (*)())arg;
</pre>
This warning can safely be ignored.
<P>
When linking (loading) programs on IRIX 4.0.5 which use LIBRT and thus
use the SGI multi-processing library <b>-lmpc</b>, the following
spurious warning messages are produced:
<pre>
/usr/bin/ld:^M
Warning: _oserror: multiply defined
        previous (used) definition from '/usr/lib/libmpc.a';
        new (ignored) definition from '/usr/lib/libc_s.a'
Warning: _setoserror: multiply defined
        previous (used) definition from '/usr/lib/libmpc.a';
        new (ignored) definition from '/usr/lib/libc_s.a'
</pre>
These warnings can safely be ignored;  we could find no way to suppress them.
<P>
Most importantly, the "moss" and "world" benchmarks no longer produce
images that match the reference images.
This results in the "run.sh" script printing these messages:
<pre>
+++++ moss
pixcmp bytes:  786425 matching,       5 off by 1,       2 off by many
moss.pix: WRONG WRONG WRONG WRONG WRONG WRONG
+++++ world
pixcmp bytes:  786417 matching,      12 off by 1,       3 off by many
world.pix: WRONG WRONG WRONG WRONG WRONG WRONG
</pre>
The difference seems to occur at three locations where the eye ray
just grazes the edge of the yellow torus.  Since these differences do
not occur on other architectures or on more recent SGI software
releases, our current assumption is that this is probably due to a
compiler or OS-release specific interaction with the IEEE rounding modes
of the processor hardware. As we are about to phase out Irix 4.0.5 in
favor of Irix 5.3 for all ARL SGI machines, this puzzle does not seem
worth pursuing.
<H3>
SGI IRIX 5.2</H3>
<P>
When compiling on IRIX 5.2 using shared libraries, many times
the SGI loader will produce the following warning(s):
<pre>
ld:
The shared object /usr/lib/libm.so did not resolve any symbols.
        You may want to remove it from your link line.
</pre>
This warning can safely be ignored.
The documentation states that the <b>-S</b> option given to the loader
will suppress loader warnings like this, but when specified, causes
the loader to issue an additional warning stating that the <b>-S</b>
option is unimplemented.
<H3>
SGI IRIX 6.0</H3>
<P>
The hardware semaphore support needed for running RT and LGT in
multi-processor mode is broken in Irix 6.0.  SGI claims that this
is fixed in Irix 6.0.1;  you will need to modify librt/machine.c
to eliminate the software workaround currently employed.
<P>
When building 64-bit executables under Irix 6.0, the SGI graphics
library "GL" is not supported.  SGI tells us that they only intend
to support Open-GL on 64-bit platforms.  We have OpenGL modules for
LIBFB and MGED underway, but they are not ready yet.  In the meantime,
Irix 6.0 platforms are limited to using the remote framebuffer and
X11 interfaces.
<P>
XMGED can not yet be successfully compiled on Irix 6.0, either.  Bummer.
<H2>
ALLIANT WARNINGS</H2>
<P>
Under Concentrix 5.0, the module <b>librt/machine.c</b> causes the
optimizer to dump core.  If you compile it without
optimization before compiling everything else, this will avoid the trouble:
<pre>
cd librt

cc -ce -I../h -DBSD=42 -c ../librt/machine.c

cake
</pre>
<H2>
CRAY WARNINGS</H2>
<P>
When performing multi-tasking on either the XMP or the Cray-2,
the librt/timerunix.c routine has great difficulty in collecting
correct timing.  On the average, one run in four will have correct
timing data.  This is due to a weird interaction between the
Cray multi-tasking library and the UNIX times() system call.
In particular, the multi-tasking library provides an arbitrary
mapping between ``virtual cpu'' and tfork()-ed UNIX process, so
that the ``main'' thread of control can land in any process in
the multi-tasking group \(em but only one of those processes is
the parent process, where timing data is being collected.
Presently, there is no known fix, except to re-run the benchmarks
many times, and only use timing data from runs where the
``rt_parallel: PID changed ...'' warning does not occur.
<P>
Ignore warning messages of this form:
<pre>
 *** *** SC1130 [caution ] < File = ../librt/vert.c, line = 337 > :

         Code was not generated for the block beginning at or corresponding to this statement (or part of it), because there is no path to it or it is not necessary.
</pre>
<P>
In <b>remrt</b>, ignore the error messages:
<pre>
 *** *** SC065 [caution ] < ../remrt/remrt.c, Line = 29, File = /usr/include/netdb.h line = 34 > :

         Invalid characters appear before a new-line in the '#else' directive.

 *** *** SC065 [caution ] < ../remrt/remrt.c, Line = 29, File = /usr/include/netdb.h line = 37 > :

         Invalid characters appear before a new-line in the '#endif' directive.
</pre>
and the like;  they are due to non-ANSI-C constructs in system include
files provided by Cray.
<P>
It is safe to ignore the self-laudatory messages of the form:
<pre>
* Loop Vectorized at 181 in foo$c
</pre>
<P>
Various remarks from CFT77 regarding the Whetstone tests
can also be ignored.
<H2>
CONVEX Warnings</H2>
When compiling on the Convex it is safe to ignore messages of the forms:
<pre>
cc: Warning on line 849 of machine.c: saw asm statement in 'RES_ACQUIRE',
optimization level reduced to -O0.

cc: Warning on line X of fbstretch.c: expression statement has no effect
</pre>
<H2>
SUN PROBLEMS</H2>
<P>
A problem with keyboard command input to <b>mged</b> being ignored
has been seen
when running <b>mged</b> on a color Sun workstation running SunOS 3.4.
This problem does <I>not</i> affect C-Shell (<b>csh</b>) users,
only Bourne Shell (<b>/bin/sh</b>) users, and has something to do with
SunView changing the process group of <b>mged</b> when the local graphics
window is opened.
If you are a Bourne Shell user and you experience this problem,
try running <b>csh</b> before starting <b>mged</b>.
<H2>
DEC ALPHA PROBLEMS</H2>
<P>
When the DEC loader builds a shared library, it insists on printout out
a list of all the external symbols referenced by that library, even
though the -S flag has been given.  These messages are unsightly
but not harmful.
<H1>
ENHANCEMENTS</H1>
<P>
If you develop additional software for the BRL-CAD environment that
you would be willing to share, please send it to us for inclusion
in the next release.
The first such inclusion was the Utah Raster Toolkit, included "as is"
in the directory contributed and integrated into the system in the
directories tools and librle.
Note that ARL considers the RLE format a long-term image storage format,
with pix(5) format used for image manipulation, while Utah uses RLE
format for all manipulation stages as well.
<H1>
UPGRADING FROM RELEASE 1.20 to 2.0</H1>
<P>
Release 2.0
contains only minor external changes from Release 1.20,
but for complete safety, you should save the old binary to "conv/g2asc"
someplace safe, so that if you find the binary format of the database
incompatible you can convert your old databases from binary to ASCII
form. Having to do this is system dependent (only Sun, SGI, and Alliant
users are likely to be affected), but it is difficult to recover from
without having saved the old converter (or your old distribution tape).
<H1>
UPGRADING FROM RELEASE 2.0 to 2.3</H1>
<P>
Primarily, Release 2.3 is a maintenance release, with lots of little
nits resolved, along with a few new features being added.
The major weak area is
still Sun display support.  In particular, using RT from within MGED
fails miserably.
<P>
This release contains different and better support for multiple lights
in RT, along with a standardized shader interface, and stackable
shaders. Support for polygonal objects is now correct, but slow. The
spline code has been significantly improved. Some contributed code for
the Raster Technologies One/80 has been included, but is untested.  The
library for procedurally generating databases ``libwdb'' is now
included, along with some example uses in the directory ``proc-db''.
The program ``rtwalk'' generates a viewpoint animation control script
that takes the eye between given start and end points, without walking
through any geometry.  This is especially interesting when used on
complex scenes like those made by proc-db/clutter.c.
<H1>
UPGRADING FROM RELEASE 2.3 to 3.0</H1>
<P>
Release 3.0 introduces a great many new features;  too many to itemize here.
In general there should be no difficulty upgrading from Release 2.3
to Release 3.0, with one exception.
<P>
All earlier editions of the BRL-CAD package used Version 2 of the Utah
``RLE'' (Run-Length Encoded) image format.
The Utah Raster Toolkit uses Version 3, which is incompatible.
In BRL-CAD Release 3.0, this latest Utah RLE format is adopted,
to permit complete interoperability with all the Utah Toolkit software.
<H1>
UPGRADING FROM RELEASE 3.0 to 3.7</H1>
<P>
Release 3.7 is a maintenance release.
Significant effort went into providing good support
for the full line of SGI 4-D workstations.
This included making the SGI 4-D
framebuffer support work efficiently.
Both color and monochrome Sun workstations are now supported,
both in <b>mged</b> and in <b>libfb</b>.
There is now support for X-windows
in both <b>mged</b> and in <b>libfb</b>.
<P>
Some new features have been added, such as sliders for <b>mged</b>.
This release also includes a network distributed version of
the ray tracer, <b>remrt</b>.
Support for each kind of primitive geometry has now been largely
concentrated in the relevant <b>librt</b> module.
Common database-handling code has been moved entirely into <b>librt</b>.
See the file <b>doc/rel3.1.doc</b> for more details.
<P>
There have been no file format changes.
<H1>
UPGRADING FROM RELEASE 3.7 to 4.0</H1>
<P>
Release 4.0 is a major features release.
Binary geometry databases (``.g'' files) are upwards compatible from
Release 3.7 to Release 4.0, but <I>not</i> backwards compatible.
In order to move a geometry database from a 4.0 system back to a 3.7
system, it is necessary to convert it to ASCII form with <b>g2asc</b>.
The ASCII format is unchanged.
<P>
Release 4.0 contains an implementation of Kevin Weiler's n-Manifold Geometry
capability, which can be used to convert CSG models into faceted
boundary-representation approximations of the original shapes.
Note that this software is still experimental in this release, and can only
operate on very simple cases.
<P>
There are lots of new image processing and signal processing tools.
<H1>
UPGRADING FROM RELEASE 4.0 to 4.4</H1>
<P>
Release 4.4 is a maintenance release.
Binary geometry databases (``.g'' files) are upwards compatible from
Release 4.0 to Release 4.4, but <I>not</i> backwards compatible.
Many new tools are provided as well.
<P>
The NMG database support, converters, import/export routines,
MGED visualization, and MGED editing support are all operational and stable.
LIBRT is able to ray-trace NMG solid from the database (either imported
via a converter or created using MGED's <b>facetize</b> command).
This code is very young, so if you encounter difficulty please submit a bug
report.
The NMG boolean code used by MGED's <b>ev</b> command still fails on
a non-trivial number of cases.  Only about 2/3 of the M-2 Bradley can
be automatically converted.  It is anticipated that there will be
substantial improvements in the robustness of this code as the support
of the new LIBRT NMG ray-tracer is exploited.
<P>
This release contains data structure, import/export, and MGED
visualization support for trimmed NURBS NMGs ("t-NURBS NMGs"). However
there is no support for ray-tracing such objects yet. We plan on
releasing BRL-CAD Release 5.0 as soon as (1) t-NURBS NMGs can be
ray-traced by LIBRT, and (2) everything has been converted to the new
".g" database file format.
<P>
Finally, Release 4.4 includes a very polished X-windows version of MGED
dubbed XMGED, and an experimental TCL version of MGED dubbed TMGED.  TCL
provides MGED with a powerful interpreted command language that has
variables and formulas, as well as access to X11 widgets via the Tk
package and user extensibility.
When XMGED and TMGED are merged in a future release, expect a quantum
improvement in the power of MGED!
<H1>
COMMUNICATION</H1>
<P>
You are invited to participate in the InterNet electronic mailing lists
on the BRL-CAD software, which are listed at
<a href="http://sourceforge.net/mail/?group_id=105292">on the Sourceforge project site</a>
Bug reports and discussions of new features
are the main topics;  volume of messages has been light (so far).
Direct your bug reports to <a href="mailto:devs@brlcad.org">devs@brlcad.org</a> if you simply wish to make a report without subscribing.
</center>
General information and published reports on BRL-CAD is also available on the main website.
<P>
It is our intention to make substantial additional use of the
World-Wide-Web in the coming months.
</BODY></HTML>
